home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / libdl / dlsym.z / dlsym
Encoding:
Text File  |  2002-10-03  |  4.8 KB  |  104 lines
  1. DLSYM(3C)                                             Last changed: 3-11-99
  2.  
  3.  
  4. NNAAMMEE
  5.      ddllssyymm - Gets the address of a symbol in shared object
  6.  
  7. SSYYNNOOPPSSIISS
  8.      cccc [_o_p_t_i_o_n_s ...] _f_i_l_e ... --llcc [_l_i_b_r_a_r_y ...]
  9.  
  10.      ##iinncclluuddee <<ddllffccnn..hh>>
  11.  
  12.      vvooiidd **ddllssyymm((vvooiidd **_h_a_n_d_l_e,, ccoonnsstt cchhaarr **_n_a_m_e));;
  13.  
  14. IIMMPPLLEEMMEENNTTAATTIIOONN
  15.      IRIX systems
  16.  
  17. DDEESSCCRRIIPPTTIIOONN
  18.      ddllssyymm obtains the address of a symbol defined within a shared object
  19.      previously opened by ddllooppeenn, ssggiiddllooppeenn__vveerrssiioonn, or ssggiiddllaadddd.  It
  20.      accepts the following arguments:
  21.  
  22.      _h_a_n_d_l_e    The value returned by a call to ddllooppeenn(3C).  ddllcclloossee(3C)
  23.                must not have been used to close the corresponding shared
  24.                object.
  25.  
  26.      _n_a_m_e      The symbol's name as a character string.  ddllssyymm  searches
  27.                for the named symbol in all shared objects loaded
  28.                automatically as a result of loading the object referenced
  29.                by _h_a_n_d_l_e.  For more information, see ddllooppeenn(3C).
  30.  
  31.                The named object is searched and then the library list of
  32.                the DSO opened on _h_a_n_d_l_e is searched (in a pre-order,
  33.                breadth-first search of all listed DSOs).  The first visible
  34.                symbol with the requested name (weak or strong) is returned.
  35.  
  36.      For information on how names are generally resolved, as distinct from
  37.      ddllssyymm resolution, and on symbol visibility see the NAMESPACE ISSUES
  38.      section of the ddllooppeenn(3C) man page.
  39.  
  40.      For names on the handle returned by ddllooppeenn((((cchhaarr **))00,,_f_l_a_g_s)), the name
  41.      resolution is in rrlldd(5)-list order according to the internal list
  42.      maintained at run time by rrlldd(5).  For other handles, name resolution
  43.      is in breadth-first order based on following the library-list
  44.      (liblist) of the DSO named in the ddllooppeenn((_n_a_m_e,,_f_l_a_g_s)) call.  Normally,
  45.      these searches result in the same sequence of DSOs being searched, but
  46.      the former searches file aa..oouutt and all globally visble DSOs.  The
  47.      latter, however, searches only DSOs in the transitive closure of the
  48.      library-list of the named DSO.
  49.  
  50. RREETTUURRNN VVAALLUUEESS
  51.      When casting the return type of ddllssyymm to be a function pointer, the C
  52.      or C++ compiler might emit the following warning:
  53.  
  54.       warning(1048): cast between pointer-to-object and pointer-to-function
  55.  
  56.      While a cast from pointer-to-data to pointer-to-function is not
  57.      necessarily portable to all systems, which is what the warning means,
  58.      the cast and the resulting call perform correctly on any system that
  59.      supports ddllssyymm.  When getting function addresses, one could define a
  60.      function such as the one in the following example and call it instead
  61.      of ddllssyymm:
  62.  
  63.           int (*dlsymfunc(void *handle,char *name))();
  64.           int (*dlsymfunc(void *handle,char *name))()
  65.           {
  66.                   return (int (*)())dlsym(handle,name);
  67.           }
  68.  
  69.      This would have the effect of moving the warning message to a single
  70.      spot in the program (the ddllssyymmffuunncc definition) so that the rest of the
  71.      code does not generate this warning.
  72.  
  73.      If _h_a_n_d_l_e does not refer to a valid object opened by ddllooppeenn(3C), or if
  74.      the named symbol cannot be found within any of the objects associated
  75.      with _h_a_n_d_l_e, ddllssyymm returns NNUULLLL.  More detailed diagnostic information
  76.      is available through ddlleerrrroorr(3C).
  77.  
  78. EEXXAAMMPPLLEESS
  79.      The following example shows how one can use ddllooppeenn(3C) and ddllssyymm to
  80.      access either function or data objects.  For simplicity, error
  81.      checking has been omitted.
  82.  
  83.           void *handle;
  84.           int i, *iptr;
  85.           int (*fptr)(int);
  86.  
  87.           /* open the needed object */
  88.           handle = dlopen("/usr/mydir/libx.so", RTLD_LAZY);
  89.  
  90.           /* find address of function and data objects */
  91.           fptr = (int (*)(int))dlsym(handle, "some_function");
  92.  
  93.           iptr = (int *)dlsym(handle, "int_object");
  94.  
  95.           /* invoke function, passing value of integer as a parameter */
  96.  
  97.           i = (*fptr)(*iptr);
  98.  
  99. SSEEEE AALLSSOO
  100.      ddllcclloossee(3C), ddlleerrrroorr(3C), ddllooppeenn(3C), ssggiiddllaadddd(3C),
  101.      ssggiiggeettddssoovveerrssiioonn(3C)
  102.  
  103.      This man page is available only online.
  104.